Skip to content

Add structured Sphinx-based documentation scaffold (issue #61) - #230

Closed
varma1221 wants to merge 9 commits into
mllam:mainfrom
varma1221:docs/improve-api-structure
Closed

Add structured Sphinx-based documentation scaffold (issue #61)#230
varma1221 wants to merge 9 commits into
mllam:mainfrom
varma1221:docs/improve-api-structure

Conversation

@varma1221

@varma1221 varma1221 commented Feb 22, 2026

Copy link
Copy Markdown
Contributor

Describe your changes

This PR introduces a structured Sphinx-based documentation scaffold for Neural-LAM, addressing #61.

The idea was to build something that can actually grow rather than just showing that Sphinx works. The documentation is organized into clear sections (introduction, installation, api) and uses Sphinx with autodoc, napoleon, and myst_parser to generate API documentation directly from existing docstrings.

Instead of documenting only the top-level package, this PR documents modules explicitly (interaction_net, metrics, utils, vis, models, datastore, weather_dataset, train_model) making it easier to add new modules later.

The configuration enables documentation builds without requiring the full ML training environment by using autodoc_mock_imports for heavy scientific and ML dependencies.

While integrating Sphinx, module-level import side effects were observed (e.g., path construction and runtime-dependent operations). These may produce warnings during documentation builds. This PR does not modify core module behavior but establishes a stable documentation structure.

Documentation Dependencies

The following are required only for building documentation:

  • sphinx
  • furo
  • myst-parser

These do not affect runtime training dependencies.

Issue Link

addresses #61

Type of change

  • 🐛 Bug fix (non-breaking change that fixes an issue)
  • ✨ New feature (non-breaking change that adds functionality)
  • 💥 Breaking change (fix or feature that would cause existing functionality to not work as expected)
  • 📖 Documentation (Addition or improvements to documentation)

Checklist before requesting a review

  • My branch is up-to-date with the target branch
  • I have performed a self-review of my code
  • For any new/modified functions/classes I have added docstrings that clearly describe its purpose, expected inputs and returned values
  • I have placed in-line comments to clarify the intent of any hard-to-understand passages of my code
  • I have updated the README to cover introduced code changes
  • I have added tests that prove my fix is effective or that my feature works
  • I have given the PR a name that clearly describes the change, written in imperative form
  • I have requested a reviewer and an assignee (I do not have write access)

Checklist for reviewers

Each PR comes with its own improvements and flaws. The reviewer should check the following:

  • the code is readable
  • the changes are easy to maintain

Author checklist after completed review

  • I have added a line to the CHANGELOG describing this change

Checklist for assignee

  • PR is up to date with the base branch
  • the tests pass
  • (if applicable) the PR is assigned to the next milestone
  • author has added an entry to the changelog

@varma1221

varma1221 commented Feb 22, 2026

Copy link
Copy Markdown
Contributor Author

Hi @joeloskarsson and @leifdenby
I’ve added a structured Sphinx documentation scaffold addressing #61. I’d appreciate feedback on whether this direction aligns with the intended documentation roadmap. If appropriate, could you please assign a reviewer?

@leifdenby

leifdenby commented Feb 23, 2026

Copy link
Copy Markdown
Member

Thank you for working on this @varma1221! Could you upload the resulting output somewhere so I could take a look? It would also be great if you could look into how to get this integrated with a ci action so that we can automatically push the rendered docs to readthedocs for example. I have tried to look at this before, but didn't finish it... The ideal would be that each PR had its own temporary URL where the rendered docs can be viewed. Is that possible?

@Jayant-kernel Jayant-kernel mentioned this pull request Feb 23, 2026
Open
@varma1221

varma1221 commented Feb 23, 2026

Copy link
Copy Markdown
Contributor Author

Thank you so much for the feedback, @leifdenby.
I've zipped up the locally rendered docs/build/html folder and attached it directly to this comment so you can take a look at the output.
neural_lam_docs_preview.zip

Before I start on the CI integration, I want to make sure I understand the preferred setup. Is there already a ReadTheDocs project configured for neural-lam, or would creating that foundation (like a .readthedocs.yaml file) be part of this PR?

I ask because enabling per-PR preview URLs requires access to the ReadTheDocs admin dashboard, so I want to know what's already in place before wiring up the workflow.

@varma1221

varma1221 commented Feb 24, 2026

Copy link
Copy Markdown
Contributor Author

Hi @leifdenby, I've pushed the CI and Read the Docs integration.

  • .readthedocs.yml configures Read the Docs to build the Sphinx documentation.
  • .github/workflows/docs.yml validates the docs build on every push and pull request, so issues like broken docstrings or missing imports are caught early. It uses uv, consistent with the rest of the project.

Once the repository is connected on Read the Docs and pull request builds are enabled, each PR should automatically receive its own temporary preview URL via RTD's PR build feature.

Let me know if this setup aligns with what you had in mind, and I'm happy to adjust if needed.

@sadamov

sadamov commented Feb 26, 2026

Copy link
Copy Markdown
Collaborator

@Mohit-Lakra from #272 has a very similar implementation and is already hosting the docs on his github page. Do you think you could cooperate on this issue and find a common solution?

@varma1221

varma1221 commented Feb 27, 2026

Copy link
Copy Markdown
Contributor Author

Hi @sadamov, thanks for the heads up. I've had a look at @Mohit-Lakra's PR #272 and his live demo - the sphinx-autoapi approach is technically stronger, particularly since it avoids the need to mock heavy dependencies at build time.

I'm happy to collaborate. @Mohit-Lakra, would it make sense to make it combine efforts? I could contribute the .readthedocs.yaml and CI workflow from this PR into your branch, and we can consolidate on the Jupyter Book + sphinx-autoapi stack. Let me know how you'd like to proceed.

@Mohit-Lakra

Mohit-Lakra commented Feb 27, 2026

Copy link
Copy Markdown
Contributor

hey @varma1221 — yeah that makes sense, the autoapi approach sidesteps the whole mock imports headache. your readthedocs config is solid though and the per-PR preview URL thing is something leif specifically asked about so it'd be good to bring that in. if you want to just send it over i'll integrate it and add you to the changelog, or we can figure out the best way to combine — either works for me 🙌

@varma1221

varma1221 commented Feb 27, 2026

Copy link
Copy Markdown
Contributor Author

Following up - coordinating with @Mohit-Lakra to port the .readthedocs.yaml and CI workflow into his branch (#272). Will close this PR once that contribution is in place.

@sadamov sadamov added documentation Improvements or additions to documentation enhancement New feature or request cicd labels Mar 1, 2026
@sadamov sadamov added the duplicate This issue or pull request already exists label Mar 15, 2026
This was referenced Mar 18, 2026
Closed
Closed
Closed
Closed
Closed
@sadamov sadamov mentioned this pull request Mar 30, 2026
Closed
@sadamov

sadamov commented Mar 31, 2026

Copy link
Copy Markdown
Collaborator

@varma1221 just doing some housekeeping. Did you complete your contribution to #272 so that this PR can be closed, or not yet?

@varma1221

varma1221 commented Mar 31, 2026

Copy link
Copy Markdown
Contributor Author

Hi @sadamov yes, the .readthedocs.yaml from this PR was contributed to #272. Happy for this to be closed

@sadamov sadamov closed this Mar 31, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

cicd documentation Improvements or additions to documentation duplicate This issue or pull request already exists enhancement New feature or request

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

4 participants

@varma1221 @leifdenby @sadamov @Mohit-Lakra